Add show-list-prefer-prerendered pattern (CS-12147)#97
Merged
Conversation
Steers card authors (and AI) toward the cheap prerendered @context.searchResultsComponent stream for display lists, and away from the instance-hydrating getters (getCards / getCardCollection / store.search) that trigger a server loadLinks + serialization + Store hydration per row. - New boxel-patterns pattern `show-list-prefer-prerendered` (README + example.gts) with a cost table, the "when a data-getter is genuinely needed, scope to the current realm" guidance, and a side-by-side cheap-vs-hydrated example. - Register it in boxel-patterns/SKILL.md (Show) and glossary.md. - Cross-link from the sibling patterns show-card-list-with-views and show-table-from-query. - Frame the query-systems.md "when to use what to query cards" decision as a cost decision and point to the pattern. Defense-in-depth — a nudge toward the cheap path, not enforcement. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QboXNnsmCeFyQ76oNwVMXM
Staging Workspace Sync SuccessfulSuccessfully synced changes to staging workspace Sync Details |
Allowlist the read-only mcp__Linear__get_issue tool to reduce permission prompts (from /fewer-permission-prompts). Config only; no effect on the skill tree. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QboXNnsmCeFyQ76oNwVMXM
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new Boxel pattern that guides authors to prefer prerendered result streams for list UIs (via @context.searchResultsComponent) and frames “which query API to use” as a cost/scalability decision, with cross-links from related docs and patterns.
Changes:
- Introduces the
show-list-prefer-prerenderedpattern (README +example.gts) emphasizing prerendered list rendering and realm-scoped instance hydration only when truly needed. - Updates query guidance and pattern docs to cross-link and highlight the cost tradeoff between prerendered entries vs hydrating
CardDefinstances. - Adds a
.claude/settings.jsonfile enabling a Linear MCP permission (not mentioned in the PR description).
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/glossary.md | Registers the new pattern in the glossary’s “Show” section. |
| skills/boxel/references/query-systems.md | Reframes “when to use what” query guidance as a cost decision and points to the new pattern. |
| skills/boxel-patterns/SKILL.md | Registers the new pattern in the Show patterns list. |
| skills/boxel-patterns/patterns/show-table-from-query/README.md | Cross-links to the new pattern in “See also”. |
| skills/boxel-patterns/patterns/show-list-prefer-prerendered/README.md | Adds the new pattern documentation and recipe. |
| skills/boxel-patterns/patterns/show-list-prefer-prerendered/example.gts | Adds an example CardDef showing prerendered list rendering + commented scoped hydration alternative. |
| skills/boxel-patterns/patterns/show-card-list-with-views/README.md | Cross-links to the new pattern in “See also”. |
| .claude/settings.json | Adds Claude Code tool permissions configuration (Linear MCP). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Both Source references now point at the catalog realm consistently. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QboXNnsmCeFyQ76oNwVMXM
The permission allowlist is local Claude Code config unrelated to the CS-12147 pattern work, so it shouldn't live in this public repo. Keep it on disk for local use and ignore it going forward. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QboXNnsmCeFyQ76oNwVMXM
lukemelia
approved these changes
Jul 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The card-facing search APIs split by cost, and the ergonomic-sounding ones hydrate:
@context.searchResultsComponent— renders the prerenderedentrystream (HTML, lazily hydrated per row). Cheap.getCards/getCardCollection/store.search— return liveCardDefinstances → serverloadLinks+ serialization + Store hydration for every matching row. Expensive.Nothing in the skill tree steered authors (or AI) toward the cheap path — a display list could silently become an N-round-trip hydration, which is the class of userland code that could push the server into overload. This is the defense-in-depth companion to the platform-side bounds: a nudge, not enforcement.
What changed
boxel-patterns/patterns/show-list-prefer-prerendered/(README +example.gts), a sibling toshow-card-list-with-views/show-table-from-query:realmURLSymbol), so a hydrating query stays bounded to one realm rather than the whole federation.example.gts: the cheap@context.searchResultsComponentdefault, plus a commentedgetCards/store.searchpath marked "only when you read/mutate the instances," scoped to the current realm.boxel-patterns/SKILL.md(Show) andskills/glossary.md.query-systems.md"when to use what to query cards" decision as a cost decision and pointed it at the new pattern.Notes
validated: source-proven— every mechanic in the example (searchResultsComponent,getCards,realmURLscoping) is already proven in live realms and documented inquery-systems.md; the pattern distills the decision.🤖 Generated with Claude Code
https://claude.ai/code/session_01QboXNnsmCeFyQ76oNwVMXM
Generated by Claude Code